namespace FineCollection.Intf
{
    /// <summary>
    /// An ordered set (read only).
    /// As a set, all items are different and nulls are not allowed.
    /// </summary>
    /// <typeparam name="T">type of an item.</typeparam>
    public interface RRandomSet<T> : ROrderSet<T>, RRandomList<T>
    {
        /// <summary>
        /// Looks for the specified item, 
        /// or for the possible position where this item may be placed
        /// if this item is not in the collection.
        /// </summary>
        /// <param name="item">an item to look for, must not be null.</param>
        /// <param name="found">true if found, false otherwise.</param>
        /// <param name="position">
        /// <ul>
        /// <li>if the item is found - the position of this item;</li>
        /// <li>if the item is not found and the set is not empty -
        ///        the position of the nearest item larger than the specified one;</li>
        /// <li>if all items of the set are less than the specified one - 
        ///        the <see cref="RRandomList{T}.LastIndex"/> + 1;</li>
        /// <li>if the set is empty - 
        ///        the <see cref="RRandomList{T}.FirstIndex"/>.</li>
        /// </ul>
        /// </param>
        /// <exception cref="NullItemsException">when the specified item is null.</exception>
        void Find(T item, out bool found, out int position);


        /// <summary>
        /// Looks for the specified item.
        /// </summary>
        /// <param name="item">an item to look for, may be null.</param>
        /// <returns>index of the found item, 
        ///          or <see cref="int.MinValue"/> if not found.</returns>
        /// <remarks>
        /// When the specified item is null - 
        /// does nothing and returns <see cref="int.MinValue"/>.
        /// </remarks>
        int IndexOf(T item);
    }
}